From 0201a3e92bbab1eca481b178b4b09bea88e33603 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Sat, 25 Jul 2026 20:50:26 +0000 Subject: [PATCH] Re-work the OBS, DYADS, and PANTGRUNT_VIEWS docs Add examples, interlink and inter-relate the explanatory text, and be more tutorial. --- doc/src/views/dyads.m4 | 74 ++++++++++++++++----- doc/src/views/obs.m4 | 110 ++++++++++++++++++++++--------- doc/src/views/pantgrunts_view.m4 | 16 ++++- 3 files changed, 152 insertions(+), 48 deletions(-) diff --git a/doc/src/views/dyads.m4 b/doc/src/views/dyads.m4 index cff1105..b237c43 100644 --- a/doc/src/views/dyads.m4 +++ b/doc/src/views/dyads.m4 @@ -31,8 +31,22 @@ DYADS |DYADS_summary| -The view puts the individual performing an action and the -individual receiving the action in separate columns. +This view extends the |OBS| view with columns for the individual +performing the action and the individual receiving the action. +It puts the individual performing an action and the individual +receiving the action in separate columns of one row.\ [#f1]_ + +The DYADS view can be a core component when querying dyadic +interactions. +Having said that, instead of copying and altering the example |DYADS| +query given below, it may be best to alter and use the +|PANTGRUNTS_VIEW|\ 's ``SELECT`` statement. +It uses DYADS to supply the date, time, and participants and adds to +that the detailed data on pantgrunts found in |PANTGRUNTS|. +Queries similar to the ``SELECT`` statement found within the +|PANTGRUNTS_VIEW| definition may often be the simplest way to report +on other behaviors recorded as dyadic interactions -- groomings, +matings, aggressions, etc. The Style column indicates whether the action is directed, mutual, or of unknown direction. @@ -53,22 +67,34 @@ The possible values and their meaning are: There is no meaning to the placement of the interacting individuals into the Actor and Recipient columns. -This view extends the |OBS| view with columns for the individual -performing the action and the individual receiving the action. +.. _DYADS_grooming_example_anchor: -The DYADS view can be a core component when querying dyadic -interactions. +The following example finds every (unique) grooming event, from the +groomings recording during B-Record interval scanning, and the +individual doing the grooming, whether or not the grooming is +reciprocal: -For an example use of the DYADS view, see the |PANTGRUNTS_VIEW| +.. code-block:: sql + :caption: Unique B-Record interval scan groomers + + SELECT dyads.wid, dyads.eid, dyads.date + , dyads.start AS time + , dyads.actor AS animid + FROM dyads + JOIN groom_scans_b ON (groom_scans_b.eid = dyads.eid) + WHERE (dyads.style = 'sdb_directed_style' + OR dyads.style = 'sdb_mutual_style') + AND NOT groom_scans_b.duplicate + ORDER BY dyads.actor, dyads.date, dyads.start; + +The above example produces the same output as :ref:`the grooming query +` example presented in the |OBS| documentation. -It joins the DYADS view with the |PANTGRUNTS| table to provide a -more-or-less complete report on pantgrunt data. -It uses DYADS to supply the date, time, and participants and adds to -that the detailed data on pantgrunts found in |PANTGRUNTS|. -Queries similar to the ``SELECT`` statement found within the -|PANTGRUNTS_VIEW| definition can be written to report on the other -behaviors recorded as dyadic interactions -- groomings, matings, -aggressions, etc. + +Again, for another use of the DYADS view, see the |PANTGRUNTS_VIEW| +documentation. +It joins the DYADS view with the |PANTGRUNTS| table +to provide a more-or-less complete report on pantgrunt data. .. _DYADS_Definition: @@ -132,7 +158,7 @@ Columns of the DYADS View | | | the action, or mutually acting | +-----------------+-------------------------------------------------+---------------------------------------------------------------------+ | Actor | |ROLES|.\ |ROLES.Participant| | The |BIOGRAPHY_DATA|.\ |BIOGRAPHY_DATA.AnimID| of the individual | - | | | performing the action, or mutually actintg | + | | | performing the action, or mutually acting | +-----------------+-------------------------------------------------+---------------------------------------------------------------------+ | Recipient | |ROLES|.\ |ROLES.Participant| | The |BIOGRAPHY_DATA|.\ |BIOGRAPHY_DATA.AnimID| of the individual | | | | receiving the action, or mutually acting | @@ -232,3 +258,19 @@ DELETE To make this process easier, there may be a view available. For example, the |PANTGRUNTS_VIEW| deletes rows from the |PANTGRUNTS| table before deleting rows from DYADS. + + +.. rubric:: Footnotes + +.. [#f1] + The DYADS view demonstrates how to alias table names using the SQL + ``AS`` keyword, joining |ROLES| twice in the same query, which + allows both participants to appear in a single row in the query + results. + + It should not be necessary for regular users to need this technique. + The existing views are expected to embody all of the more advanced + query techniques needed in ordinary use. + Only "simple" queries are expected to be needed, queries of the + views provided -- in "simple" combination with the system's other + tables. diff --git a/doc/src/views/obs.m4 b/doc/src/views/obs.m4 index 660c5f8..93402af 100644 --- a/doc/src/views/obs.m4 +++ b/doc/src/views/obs.m4 @@ -34,12 +34,59 @@ OBS (OBservationS) OBS rows are |EVENTS| rows, but extended with the date, |BIOGRAPHY_DATA.AnimID|, and other information found on |WATCHES|. +It is important to remember that the |BIOGRAPHY_DATA.AnimID| value +presented, the OBS.\ |WATCHES.AnimID| column, is the value found in +|WATCHES|.\ |WATCHES.AnimID|. +This is *not* always the individual observed to have exhibited some +behavior or otherwise participated in the event. +*That* individual is found in a related |ROLES| row, in the |ROLES|.\ +|ROLES.Participant| column. + +The OBS.\ |WATCHES.AnimID| column contains the chimpanzee who, in some +sense, is the reason why the observers were present. +Often this is the focal of the follow that was ongoing when the event +occurred.\ [#f1]_ +Feeding station attendance observations have for their OBS.\ +|WATCHES.AnimID| value, the individual who arrived at the feeding +station.\ [#f2]_ +Other kinds of events, distinguished by their OBS.\ |EVENTS.Behavior| +values, have other rules regarding the identity of the individual +recorded in the OBS.\ |WATCHES.AnimID| column. +See the documentation of the |EVENTS| table for more information. + +Many events are expected to have the unknown individual, ``sdb_unk``, +as their OBS.\ |WATCHES.AnimID| value -- indicating that the field team +had no particular intention to conduct an observation but, instead, +happened to observe the event. +An example of this could be a pantgrunt event observed while the field +researchers were on some errand. + The OBS view is convenient when writing queries, instead of having to ``JOIN`` |EVENTS| with |WATCHES| every time behavior is queried. +Even more convenient is to use a view, one often, ultimately, based on +OBS, tailored to a specific purpose. +Like the |PANTGRUNTS_VIEW| view, which is tailored to querying +pantgrunt information. + +At the time of this writing, not many of these special purpose views +exist. +You may, instead, need to tailor some of the examples below, or code +shown in the |DYADS| view or |PANTGRUNTS_VIEW| documentation, to suit +your purpose. + For example, below is a query that returns all the arrivals and departures from the feeding station attendance records, showing bananas eaten. +Use this example as a template to query other events *not* +involving dyadic interactions. +(Events not involving pairs of individuals.) +Queries similar to the following may report on events such as feeding +bouts, location observations, other species present, colobus +enconters, etc. +From the example, substitute the appropriate table, |FOOD_EVENTS|, +|LOCATIONS_UTM|, |SPECIES_PRESENT|, |COLOBUS|, etc., and that table's +columns, in place of the |ARRIVALS_A| table and its columns. .. code-block:: sql :caption: Arrivals/departures at the feeding station with banana count @@ -51,17 +98,25 @@ bananas eaten. JOIN arrivals_a ON (arrivals_a.eid = obs.eid) ORDER BY obs.animid, obs.date, obs.start; -It is important to remember that the |BIOGRAPHY_DATA.AnimID| value -presented, the OBS.\ |WATCHES.AnimID| column, is the value found in -|WATCHES|.\ |WATCHES.AnimID|. -This is *not* always the individual observed to have exhibited some -behavior or otherwise participated in the event. -*That* individual is found in a related |ROLES| row, in the |ROLES|.\ -|ROLES.Participant| column. - -For example, grooming information is recorded in B-Record follows. -So the OBS.\ |WATCHES.AnimID| is the focal of the follow, not -necessarily the individual doing the grooming. +The above example queries events, arrivals at the feeding station, +which involve only a single individual. +These are the queries that OBS is best suited for. + +.. _OBS_grooming_example_anchor: + +The next example involves grooming, which is always recorded as being +between pairs of individuals. +Queries involving pairs, dyadic interactions, are often most easily +queried using the |DYADS| view. +But there is nothing wrong with using OBS to query dyadic +interactions. +The example below may be compared with the :ref:`example presented +` in the |DYADS| view, which +accomplishes the same purpose. + +Grooming information is recorded in B-Record follows. +So, as noted above, the OBS.\ |WATCHES.AnimID| is the focal of the +follow, not necessarily the individual doing the grooming. To find every (unique) grooming event, from the groomings recording during B-Record interval scanning, and the individual doing the grooming, whether or not the grooming is reciprocal, the |ROLES|.\ @@ -83,7 +138,8 @@ query: ORDER BY roles.participant, obs.date, obs.start; The following query returns every day every individual was observed -exhibiting a behavior\ [#f3]_: +exhibiting a behavior\ [#f3]_, or observed being a recipient or +otherwise involved in a behavior\ [#f5]_: .. code-block:: sql :caption: Individuals observed, per day, some sexual swelling excepted @@ -94,25 +150,6 @@ exhibiting a behavior\ [#f3]_: GROUP BY roles.participant, obs.date ORDER BY roles.participant, obs.date; -The OBS.\ |WATCHES.AnimID| column contains the chimpanzee who, in some -sense, is the reason why the observers were present. -Often this is the focal of the follow that was ongoing when the event -occurred.\ [#f1]_ -Feeding station attendance observations have for their OBS.\ -|WATCHES.AnimID| value, the individual who arrived at the feeding -station.\ [#f2]_ -Other kinds of events, distinguished by their OBS.\ |EVENTS.Behavior| -values, have other rules regarding the identity of the individual -recorded in the OBS.\ |WATCHES.AnimID| column. -See the documentation of the |EVENTS| table for more information. - -Many events are expected to have the unknown individual, ``sdb_unk``, -as their OBS.\ |WATCHES.AnimID| value -- indicating that the field team -had no particular intention to conduct an observation but, instead, -happened to observe the event. -An example of this could be a pantgrunt event observed while the field -researchers were on some errand. - .. _OBS_Definition: @@ -269,3 +306,14 @@ DELETE Familiarity with the database structure, the data itself, the procedures used to collect and record the data, and how all of this changed over time is critical for accurate results. + +.. [#f5] + To restrict the query so that it shows only those that actually + exhibit a behavior you would limit the rows returned based on + |ROLES|.\ |ROLES.Role| code. + What is appropriate depends on what |ROLE_CODES| rows are created and + how they are used, how they are paired with the behaviors found in + |EVENTS.Behavior| (aka, OBS.Behavior). + The best approach might be to exclude selected |ROLE_CODES|.\ + |ROLE_CODES.Role| values that are "special" because they involve + dyadic (paired) interactions. diff --git a/doc/src/views/pantgrunts_view.m4 b/doc/src/views/pantgrunts_view.m4 index 52ab72d..033e592 100644 --- a/doc/src/views/pantgrunts_view.m4 +++ b/doc/src/views/pantgrunts_view.m4 @@ -33,7 +33,21 @@ PANTGRUNTS_VIEW |PANTGRUNTS_VIEW_summary| The view puts the individual performing the pantgrunt and the -individual receiving the pantgrunt in separate columns. +individual receiving the pantgrunt in separate columns of one row. + +Use the PANTGRUNTS_VIEW as a template to query other events involving +dyadic interactions between individuals. +Queries similar to the ``SELECT`` statement found within the +PANTGRUNTS_VIEW definition, below, may report on behaviors such as +groomings, matings, aggressions, etc. +In the ``SELECT`` code below, substitute the appropriate table, +|GROOMINGS|, |MATINGS|, |AGGRESSIONS|, etc., and that table's columns, +in place of the |PANTGRUNTS| table and its columns. + +Execute your new ``SELECT`` statement. +(Cutting and pasting your ``SELECT`` statement into the code below +creates a new view. +Probably not the desired outcome.) The Style column indicates whether the pantgrunting was directed or mutual. The values of Style are those of the |DYADS|.Style column, although given -- 2.34.1